/*
 * Copyright 2009 Biz-e (info@biz-e.nl)
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 * http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package nl.biz_e.gdata.data;

import java.io.IOException;
import java.net.MalformedURLException;
import java.util.List;

import com.google.gdata.client.Query;
import com.google.gdata.data.BaseEntry;
import com.google.gdata.data.BaseFeed;
import com.google.gdata.util.ServiceException;

/**
 * @author Joost A. Bloemsma
 * @param <E>
 *        The type of entry (extends {@link BaseEntry}) to be returned by
 *        the service
 * @param <F>
 *        The type of Feed (extends {@link BaseFeed}) to be returned by the
 *        service
 * 
 */
public interface IItemManager<E extends BaseEntry<?>, F extends BaseFeed<?, ?>> {
	
	/**
	 * The basis used to generate request url's
	 */
	public static final String BASE_URL = "http://www.google.com/m8/feeds/";
	
	/**
	 * Returns a list of entries specified by the E parameter
	 * 
	 * @return List of entries
	 * @throws ServiceException
	 *         system error retrieving feed
	 * @throws IOException
	 *         error sending request or reading the feed.
	 */
	public List<E> getAll() throws IOException, ServiceException;
	
	/**
	 * Returns an entry of type E, specified by the passed id
	 * 
	 * @param id
	 *        The id of the entry to retrieve
	 * @return The entry
	 * @throws ServiceException
	 *         system error retrieving feed
	 * @throws IOException
	 *         error sending request or reading the feed.
	 */
	public E getItem(String id) throws IOException, ServiceException;
	
	/**
	 * Returns a feed of type F as a result of the passed {@link Query}.
	 * 
	 * @param query
	 *        The query to perform
	 * @return A Feed that results from the passed query
	 * @throws ServiceException
	 *         system error retrieving feed
	 * @throws IOException
	 *         error sending request or reading the feed.
	 */
	public F getFeed(Query query) throws IOException, ServiceException;
	
	/**
	 * Returns an entry identified by the passed url
	 * 
	 * @param url
	 * @return The entry
	 * @throws MalformedURLException
	 *         Invalid url
	 * @throws IOException
	 *         error sending request or reading the feed.
	 * @throws ServiceException
	 *         system error retrieving feed
	 */
	public E getEntryByUrl(String url) throws MalformedURLException,
			IOException, ServiceException;
	
	/**
	 * Inserts an entry
	 * 
	 * @param entry
	 *        the entry to insert
	 * @return It will return the inserted entry, including any additional
	 *         attributes or extensions set by the GData server.
	 * 
	 * @throws ServiceException
	 *         insert request failed due to system error.
	 * @throws IOException
	 *         error communicating with the GData service.
	 */
	public E insert(E entry) throws IOException, ServiceException;
}
